.jumbotron
  h2 貔貅开发者接口 (API version 2)
  small 接口URI前缀: /api/v2
  br
  small 返回结果格式: JSON
  br
  br
  a href='/documents/websocket_api' Websocket接口
  | &nbsp;|&nbsp;
  a href='/documents/oauth' OAuth认证接口

.panel.panel-default
  .panel-heading
    h3 Public/Private API

  .panel-body
    p 貔貅开发者接口包含两类API: Public API是不需要任何验证就可以使用的接口，而Private API是需要进行签名验证的接口。下表列出了两者的主要区别:

  table.table
    thead
      tr
        th Public API
        th Private API
    tbody
      tr
        td 无需验证
        td 需要验证
      tr
        td 无限制
        td 对于每个用户, 最多6000个请求每5分钟(平均20个请求/秒); 如果有更高需求可以联系貔貅管理员
      tr
        td 无需准备立即可用
        td 先要向貔貅管理员申请access/secret key

.panel.panel-default
  .panel-heading
    h3 如何签名 (验证)

  .panel-body
    p 在给一个Private API请求签名之前, 你必须准备好你的access/secret key. 在注册并认证通过后之后，只需访问<a href='/api_tokens'>API密钥</a>页面就可以得到您的密钥。
    p 所有的Private API都需要这3个用于身份验证的参数:
    table.table
      tr
        td access_key
        td 你的access key
      tr
        td tonce
        td tonce是一个用正整数表示的时间戳，代表了从<a href='http://en.wikipedia.org/wiki/Unix_epoch'>Unix epoch</a>到当前时间所经过的毫秒(ms)数。tonce与服务器时间不得超过正负30秒。一个tonce只能使用一次。
      tr
        td signature
        td 使用你的secret key生成的签名

    p 签名的生成很简单，先把请求表示为一个字符串, 然后对这个字符串做hash:
    pre: code
      | hash = HMAC-SHA256(payload, secret_key).to_hex

    p Payload就是代表这个请求的字符串, 通过组合HTTP方法, 请求地址和请求参数得到:
    pre: code
      | # canonical_verb是HTTP方法，例如GET
        # canonical_uri是请求地址， 例如/api/v2/markets
        # canonical_query是请求参数通过&连接而成的字符串，参数包括access_key和tonce, 参数必须按照字母序排列，例如access_key=xxx&foo=bar&tonce=123456789
        # 最后再把这三个字符串通过'|'字符连接起来，看起来就像这样:
        # GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789
        def payload
          "\#{canonical_verb}|\#{canonical_uri}|\#{canonical_query}"
        end

    p 假设我的secret key是"yyy", 那么使用SHA256算法对上面例子中的payload计算HMAC的结果是(以hex表示)：
    pre: code
      | hash = HMAC-SHA256('GET|/api/v2/markets|access_key=xxx&foo=bar&tonce=123456789', 'yyy').to_hex
             = 'e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'

    p 现在我们就可以这样来使用这个签名请求(以curl为例):
    pre: code
      | curl -X GET 'https://peatio.com/api/v2/markets?access_key=xxx&foo=bar&tonce=123456789&signature=e324059be4491ed8e528aa7b8735af1e96547fbec96db962d51feb7bf1b64dee'

.panel.panel-default
  .panel-heading
    h3 返回结果

  .panel-body
    p 如果API调用失败，返回的请求会使用对应的HTTP status code, 同时返回包含了详细错误信息的JSON数据, 比如:
    pre: code
      | {"error":{"code":1001,"message":"market does not have a valid value"}}
    p 所有错误都遵循上面例子的格式，只是code和message不同。code是貔貅自定义的一个错误代码, 表明此错误的类别, message是具体的出错信息.

  .panel-body
    p 对于成功的API请求, 貔貅则会返回200作为HTTP status code, 同时返回请求的JSON数据.
    table.table.result
      thead
        tr
          th 数据类型
          th 数据结构/示例
          th 备注
      tbody
        tr
          td Market
          td: pre: code
            | {"at":1398410899, "ticker":{"buy":"3000.0","sell":"3100.0","low":"3000.0","high":"3000.0","last":"3000.0","vol":"0.11"}}
          td
            p Market包含了某一个市场(例如btccny)的所有信息:
            p at: 以秒为单位的时间戳
            p buy/sell: 当前买入/卖出价
            p low/high: 过去24小时之内的最低/最高成交价
            p last: 最后成交价
            p vol: 过去24小时之内的总成交量
        tr
          td Member
          td: pre: code
            | {"sn":"PEA5TFFOGQHTIO","name":"foo","email":"foo@peatio.dev","activated":true,"accounts":[{"currency":"cny","balance":"100243840.0","locked":"0.0"},{"currency":"btc","balance":"99999708.26","locked":"210.8"}]}
          td
            p Member包含了某一个用户的所有信息:
            p sn: 用户的唯一编号
            p name: 用户名字
            p email: 用户email
            p activated: 用户是否已激活
            p accounts: 用户的所有账户信息, 参见Account
        tr
          td Account
          td: pre: code
            | {"currency":"cny","balance":"100243840.0","locked":"0.0"}
          td
            p Account包含了用户某一个币种账户的信息:
            p currency: 账户的币种, 如cny, btc
            p balance: 账户余额, 不包括冻结资金
            p locked: 冻结资金
        tr
          td Order
          td: pre: code
            | {"id":7,"side":"sell","price":"3100.0","avg_price":"3101.2","state":"wait","market":"btccny","created_at":"2014-04-18T02:02:33Z","volume":"100.0","remaining_volume":"89.8","executed_volume":"10.2","trades_count": 1, "trades":[{"id":2,"price":"3100.0","volume":"10.2","market":"btccny","created_at":"2014-04-18T02:04:49Z","side":"sell"}]}
          td
            p Order包含了某一个订单的所有信息:
            p id: 唯一的Order ID
            p side: Buy/Sell, 代表买单/卖单.
            p price: 出价
            p avg_price: 平均成交价
            p state: 订单的当前状态, wait, done或者cancel.  wait表明订单正在市场上挂单, 是一个active order, 此时订单可能部分成交或者尚未成交; done代表订单已经完全成交; cancel代表订单已经被撤销.
            p market: 订单参与的交易市场
            p created_at: 下单时间, ISO8601格式
            p volume: 购买/卖出数量
            p remaining_volume: 还未成交的数量. remaining_volume总是小于等于volume, 在订单完全成交时变成0.
            p executed_volume: 已成交的数量. volume = remaining_volume + executed_volume
            p trades_count: 订单的成交数，整数值。未成交的订单为0, 有一笔成交的订单为1, 以此类推。通过该字段可以判断订单是否处于部分成交状态。
            p trades: 订单的详细成交记录,参见Trade. 注意: 只有某些返回详细订单数据的API才会包含trades数据.
        tr
          td Trade
          td: pre: code
            | {"id":2,"price":"3100.0","volume":"10.2","market":"btccny","created_at":"2014-04-18T02:04:49Z","order_id":101,"side":"sell"}
          td
            p Trade代表订单撮合后形成的一笔交易:
            p id: 交易的唯一ID
            p price: 成交价
            p volume: 成交数量
            p market: 交易所属的市场
            p created_at: 成交时间
            p side: buy/sell, 买或者卖, 只有/api/v2/trades/my返回的trade才会包含这个字段,代表这个trade是由你的买单或者卖单产生的./api/v2/trades返回的trade中此字段永远为空.
            p order_id: 只有/api/v2/trades/my返回的trade才会包含这个字段，代表这个trade属于哪一个order.
        tr
          td OrderBook
          td: pre: code
            | {"asks": [...],"bids": [...]}
          td
            p OrderBook包含了当前市场的挂单信息:
            p asks: 卖单列表
            p bids: 买单列表

        tr
          td Deposits
          td: pre: code
            |
              [{"currency": "cny","amount": "520.0","fee": "0.0","txid": null,"created_at": "2014-11-29T15:24:26Z","memo": null,"done_at": null,"state": "submitting"},{"currency": "cny","amount": "1000.0","fee": "0.0","txid": "3","created_at": "2014-11-29T13:45:03Z","memo": null,"done_at": "2014-11-29T13:54:37Z","state": "accepted"}]

          td
            p Deposits 返回用户最近24小时内的充值信息:
            p currency: 充值种类
            p amount: 充值总量
            p fee: 交易费用
            p txid: 交易id
            p created_at: 创建时间
            p done_at: 处理时间
            p memo: 交易备注
            p state: 状态
            p ----state----
            p  accepted 表示 充值成功
        tr
          td Deposit
          td: pre: code
            |
              {"currency": "cny","amount": "520.0","fee": "0.0","txid": "8","created_at": "2014-11-29T15:24:26Z","memo": null,"done_at": "2014-12-02T02:46:24Z","state": "accepted"}

          td
            p Deposits 返回用户某条充值信息:
            p 属性 同上
            p 若txid 不存在
            p 返回
              {error: {code: 2012,message: "Deposit##txid=4 doesn't exist."}}


.panel.panel-default
  .panel-heading
    h3 一些例子

  .panel-body
    p 以4000CNY的价格买入1BTC:
    pre: code
      | curl -X POST 'https://peatio.com/api/v2/orders' -d 'access_key=your_access_key&tonce=1234567&signature=computed_signature&market=btccny&price=4000&side=buy&volume=1'

    p 同时创建多个委托:
    pre: code
      | curl -X POST 'https://peatio.com/api/v2/orders/multi' -d 'access_key=your_access_key&tonce=123456789&signature=computed_signature&market=btccny&orders[][price]=4000&orders[][side]=sell&orders[][volume]=0.5&orders[][price]=3999&orders[][side]=sell&orders[][volume]=0.99'

.panel.panel-default
  .panel-heading
    h3 注意事项

  .panel-body
    table.table
      thead
        tr
          th API
          th Detail
      tbody
        tr
          td POST /api/v2/order/delete
          td 取消挂单. 取消挂单是一个异步操作,api成功返回仅代表取消请求已经成功提交,服务器正在处理,不代表订单已经取消. 当你的挂单有尚未处理的成交(trade)事务,或者取消请求队列繁忙时,该订单会延迟取消. api返回被取消的订单,返回结果中的订单不一定处于取消状态,你的代码不应该依赖api返回结果,而应该通过/api/v2/order或者websocket api来得到该订单的最新状态.
        tr
          td POST /api/v2/orders/clear
          td 取消你所有的挂单. 取消挂单是一个异步操作, api成功返回代表取消请求已经提交,服务器正在处理. api返回的结果是你当前挂单的集合,结果中的订单不一定处于取消状态.

.panel.panel-default
  .panel-heading
    h3 相关库/工具列表

  .panel-body
    ul
      li: h4
        a href='http://github.com/peatio/peatio-client-ruby'
          | peatio-client-ruby (ruby)

.panel.panel-default
  .panel-heading
    h3 API列表

  .panel-body
    p 以下是详细的API列表，展开可以看到每个API的URI和可接受的参数。所有需要access_key/tonce/signature的都是Private API, 其他的则是Public API。

.row
  #swagger-ui-container.swagger-ui-wrap
